JavaScript 导入属性：加载 JSON 模块的现代化安全之道

多年来，JavaScript 开发者一直在努力解决一个看似简单的任务：加载 JSON 文件。虽然 JavaScript 对象表示法（JSON）是 Web 数据交换的事实标准，但将其无缝集成到 JavaScript 模块中却经历了一段充满样板代码、变通方法和潜在安全风险的旅程。从 Node.js 中的同步文件读取到浏览器中冗长的 `fetch` 调用，这些解决方案感觉更像是补丁，而非原生功能。那个时代现在正在结束。

欢迎来到导入属性的世界，这是一个由 TC39（ECMAScript 语言管理委员会）标准化的现代、安全且优雅的解决方案。这一特性通过简单而强大的 `with { type: 'json' }` 语法引入，正在彻底改变我们处理非 JavaScript 资产的方式，首先从最常见的 JSON 开始。本文为全球开发者提供了一份全面的指南，介绍什么是导入属性、它们解决了哪些关键问题，以及你如何立即开始使用它们来编写更简洁、更安全、更高效的代码。

旧世界：回顾 JavaScript 中处理 JSON 的方式

为了充分领会导入属性的优雅，我们必须首先了解它们所取代的旧有格局。根据环境（服务器端或客户端）的不同，开发者依赖于各种技术，每种技术都有其自身的权衡。

服务器端 (Node.js)：`require()` 与 `fs` 的时代

在多年来作为 Node.js 原生模块系统的 CommonJS 中，导入 JSON 非常简单：

// 在 CommonJS 文件中 (例如, index.js) const config = require('./config.json'); console.log(config.database.host);

这工作得很好。Node.js 会自动将 JSON 文件解析成一个 JavaScript 对象。然而，随着全球向 ECMAScript 模块（ESM）的转变，这个同步的 `require()` 函数变得与现代 JavaScript 的异步、顶层 await 特性不兼容。直接的 ESM 等价物 `import` 最初不支持 JSON 模块，迫使开发者回到更旧、更手动的方​​法：

// 在 ESM 文件中手动读取文件 (例如, index.mjs) import fs from 'fs'; import path from 'path'; const configPath = path.resolve('config.json'); const configFile = fs.readFileSync(configPath, 'utf8'); const config = JSON.parse(configFile); console.log(config.database.host);

这种方法有几个缺点：

• 冗余：单个操作需要多行样板代码。
• 同步 I/O：`fs.readFileSync` 是一个阻塞操作，在高并发应用中可能成为性能瓶颈。异步版本（`fs.readFile`）则需要更多带有回调或 Promise 的样板代码。
• 缺乏集成：它感觉与模块系统脱节，将 JSON 文件视为需要手动解析的通用文本文件。

客户端（浏览器）：`fetch` API 的样板代码

在浏览器中，开发者长期以来依赖 `fetch` API 从服务器加载 JSON 数据。虽然功能强大且灵活，但对于一个本应直接的导入操作来说，它显得过于冗长。

// 经典的 fetch 模式 let config; fetch('/config.json') .then(response => { if (!response.ok) { throw new Error('Network response was not ok'); } return response.json(); // 解析 JSON 主体 }) .then(data => { config = data; console.log(config.api.key); }) .catch(error => console.error('Error fetching config:', error));

这种模式虽然有效，但存在以下问题：

• 样板代码：每次加载 JSON 都需要类似的 Promise 链、响应检查和错误处理。
• 异步开销：管理 `fetch` 的异步特性会使应用程序逻辑复杂化，通常需要状态管理来处理加载阶段。
• 无法静态分析：因为它是一个运行时调用，构建工具无法轻松分析这种依赖关系，可能会错过优化机会。

向前一步：带断言的动态 `import()` (前身)

认识到这些挑战，TC39 委员会最初提出了导入断言 (Import Assertions)。这是迈向解决方案的重要一步，允许开发者为导入提供元数据。

// 最初的导入断言提案 const configModule = await import('./config.json', { assert: { type: 'json' } }); const config = configModule.default;

这是一个巨大的改进。它将 JSON 加载集成到了 ESM 系统中。`assert` 子句告诉 JavaScript 引擎验证加载的资源确实是 JSON 文件。然而，在标准化过程中，一个关键的语义差异浮现出来，导致其演变为导入属性。

导入属性登场：一种声明式且安全的方法

经过引擎实现者的广泛讨论和反馈，导入断言被改进为导入属性 (Import Attributes)。语法上只有细微差别，但语义上的变化是深远的。这是导入 JSON 模块的新的、标准化的方式：

静态导入： import config from './config.json' with { type: 'json' };

动态导入： const configModule = await import('./config.json', { with: { type: 'json' } }); const config = configModule.default;

`with` 关键字：不仅仅是名称变更

从 `assert` 到 `with` 的改变不仅仅是表面上的。它反映了目的上的根本转变：

• `assert { type: 'json' }`：此语法意味着加载后验证。引擎会获取模块，然后检查其是否与断言匹配。如果不匹配，则抛出错误。这主要是一个安全检查。
• `with { type: 'json' }`：此语法意味着加载前指令。它向宿主环境（浏览器或 Node.js）提供关于如何从一开始就加载和解析模块的信息。这不仅仅是一个检查，更是一个指令。

这个区别至关重要。`with` 关键字告诉 JavaScript 引擎：“我打算导入一个资源，并提供属性来指导加载过程。请使用此信息从一开始就选择正确的加载器并应用正确的安全策略。” 这使得引擎可以进行更好的优化，并在开发者和引擎之间建立更清晰的约定。

为何这是颠覆性的改变？安全性的必要

导入属性最重要的好处是安全性。它们旨在防止一类被称为 MIME 类型混淆的攻击，这种攻击可能导致远程代码执行 (RCE)。

模糊导入带来的 RCE 威胁

想象一个没有导入属性的场景，其中使用动态导入从服务器加载配置文件：

// 可能不安全的导入 const { settings } = await import('https://api.example.com/user-settings.json');

如果 `api.example.com` 的服务器被攻破了怎么办？恶意行为者可以将 `user-settings.json` 端点改为提供一个 JavaScript 文件而不是 JSON 文件，同时仍然保留 `.json` 扩展名。服务器将返回带有 `Content-Type` 头为 `text/javascript` 的可执行代码。

如果没有检查类型的机制，JavaScript 引擎可能会看到 JavaScript 代码并执行它，从而让攻击者控制用户的会话。这是一个严重的安全漏洞。

导入属性如何降低风险

导入属性优雅地解决了这个问题。当你使用带属性的导入时，你与引擎建立了一个严格的约定：

// 安全的导入 const { settings } = await import('https://api.example.com/user-settings.json' with { type: 'json' });

现在会发生以下情况：

1. 浏览器请求 `user-settings.json`。
2. 被攻破的服务器返回 JavaScript 代码和 `Content-Type: text/javascript` 响应头。
3. 浏览器的模块加载器看到响应的 MIME 类型 (`text/javascript`) 与导入属性中预期的类型 (`json`) 不匹配。
4. 引擎不会解析或执行该文件，而是立即抛出一个 `TypeError`，中止操作并阻止任何恶意代码运行。

这个简单的补充将一个潜在的 RCE 漏洞转变为一个安全的、可预测的运行时错误。它确保数据始终是数据，绝不会被意外地解释为可执行代码。

实际用例与代码示例

用于 JSON 的导入属性不仅仅是一个理论上的安全功能。它们为跨领域的日常开发任务带来了人体工程学上的改进。

1. 加载应用程序配置

这是最经典的用例。现在你可以直接静态地导入你的配置，而无需手动进行文件 I/O。

文件: `config.json` { "database": { "host": "db.production.example.com", "port": 5432, "user": "api_user" }, "featureFlags": { "newDashboard": true, "enableLogging": false } }

文件: `database.mjs` import config from './config.json' with { type: 'json' }; export function getDbHost() { return config.database.host; } console.log(`Connecting to database at: ${getDbHost()}`);

这段代码简洁、声明式，并且易于人类和构建工具理解。

2. 国际化 (i18n) 数据

管理翻译是另一个完美的适用场景。你可以将语言字符串存储在单独的 JSON 文件中，并根据需要导入它们。

文件: `locales/en-US.json` { "welcomeMessage": "Hello, welcome to our application!", "logoutButton": "Log Out" }

文件: `locales/es-MX.json` { "welcomeMessage": "¡Hola, bienvenido a nuestra aplicación!", "logoutButton": "Cerrar Sesión" }

文件: `i18n.mjs` // 静态导入默认语言 import defaultStrings from './locales/en-US.json' with { type: 'json' }; // 根据用户偏好动态导入其他语言 async function getTranslations(locale) { if (locale === 'es-MX') { const module = await import('./locales/es-MX.json', { with: { type: 'json' } }); return module.default; } return defaultStrings; } const userLocale = 'es-MX'; const strings = await getTranslations(userLocale); console.log(strings.welcomeMessage); // 输出西班牙语消息

3. 为 Web 应用加载静态数据

想象一下用国家列表填充下拉菜单或显示产品目录。这些静态数据可以放在一个 JSON 文件中管理，并直接导入到你的组件中。

文件: `data/countries.json` [ { "code": "US", "name": "United States" }, { "code": "DE", "name": "Germany" }, { "code": "JP", "name": "Japan" } ]

文件: `CountrySelector.js` (假设的组件) import countries from '../data/countries.json' with { type: 'json' }; export class CountrySelector { constructor(elementId) { this.element = document.getElementById(elementId); this.render(); } render() { const options = countries.map(country => `${country.name}` ).join(''); this.element.innerHTML = options; } } // 用法 new CountrySelector('country-dropdown');

底层工作原理：宿主环境的角色

导入属性的行为由宿主环境定义。这意味着在浏览器和像 Node.js 这样的服务器端运行时之间，实现上会有些许差异，尽管最终结果是一致的。

在浏览器中

在浏览器上下文中，该过程与 HTTP 和 MIME 类型等 Web 标准紧密耦合。

1. 当浏览器遇到 `import data from './data.json' with { type: 'json' }` 时，它会为 `./data.json` 发起一个 HTTP GET 请求。
2. 服务器接收请求并应返回 JSON 内容。关键是，服务器的 HTTP 响应必须包含 `Content-Type: application/json` 头。
3. 浏览器接收响应并检查 `Content-Type` 头。
4. 它将头的值与导入属性中指定的 `type` 进行比较。
5. 如果它们匹配，浏览器将响应体解析为 JSON 并创建模块对象。
6. 如果它们不匹配（例如，服务器发送了 `text/html` 或 `text/javascript`），浏览器将以 `TypeError` 拒绝模块加载。

在 Node.js 和其他运行时中

对于本地文件系统操作，Node.js 和 Deno 不使用 MIME 类型。相反，它们依赖于文件扩展名和导入属性的组合来决定如何处理文件。

1. 当 Node.js 的 ESM 加载器看到 `import config from './config.json' with { type: 'json' }` 时，它首先识别文件路径。
2. 它使用 `with { type: 'json' }` 属性作为一个强信号，来选择其内部的 JSON 模块加载器。
3. JSON 加载器从磁盘读取文件内容。
4. 它将内容解析为 JSON。如果文件包含无效的 JSON，则会抛出语法错误。
5. 一个模块对象被创建并返回，通常解析后的数据作为 `default` 导出。

来自属性的这个明确指令避免了歧义。Node.js 明确知道它不应尝试将该文件作为 JavaScript 执行，无论其内容如何。

浏览器和运行时支持：是否可以用于生产环境？

采用新的语言特性需要仔细考虑其在目标环境中的支持情况。幸运的是，用于 JSON 的导入属性已在整个 JavaScript 生态系统中得到迅速而广泛的采用。截至 2023 年底，它在现代环境中的支持非常出色。

• Google Chrome / Chromium 引擎 (Edge, Opera): 自 117 版本起支持。
• Mozilla Firefox: 自 121 版本起支持。
• Safari (WebKit): 自 17.2 版本起支持。
• Node.js: 自 21.0 版本起完全支持。在早期版本中（例如 v18.19.0+、v20.10.0+），它需要通过 `--experimental-import-attributes` 标志启用。
• Deno: 作为一个先进的运行时，Deno 自 1.34 版本起就支持此功能（从断言演变而来）。
• Bun: 自 1.0 版本起支持。

对于需要支持旧版浏览器或 Node.js 版本的项目，现代构建工具和打包器如 Vite、Webpack (配合适当的加载器) 和 Babel (配合转换插件) 可以将新语法转换为兼容格式，让你立即就能编写现代代码。

JSON 之外：导入属性的未来

虽然 JSON 是第一个也是最突出的用例，但 `with` 语法的设计是可扩展的。它为附加元数据到模块导入提供了一种通用机制，为将其他类型的非 JavaScript 资源集成到 ES 模块系统铺平了道路。

CSS 模块脚本

即将到来的下一个主要功能是 CSS 模块脚本。该提案允许开发者直接将 CSS 样式表作为模块导入：

import sheet from './styles.css' with { type: 'css' }; document.adoptedStyleSheets = [sheet];

当一个 CSS 文件以这种方式导入时，它会被解析成一个 `CSSStyleSheet` 对象，可以以编程方式应用于文档或 Shadow DOM。这是 Web 组件和动态样式方面的一大飞跃，避免了手动向 DOM 注入 `